fix(v3): redesign of batch completion to prevent heavy row-level contention on the BatchTaskRun by ericallam · Pull Request #2930 · triggerdotdev/trigger.dev

ericallam · 2026-01-23T15:20:36Z

No description provided.

…ention on the BatchTaskRun

changeset-bot · 2026-01-23T15:20:41Z

⚠️ No Changeset found

Latest commit: 85b84c2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

coderabbitai · 2026-01-23T15:21:02Z

Walkthrough

This pull request introduces a new tryCompleteBatchV3 function that performs batch completion with idempotent checks on sealed batches, optionally scheduling dependent attempt resumption. The function is registered as a background worker task with 30-second timeout and 5-retry limits. completeBatchTaskRunItemV3 is refactored to perform direct item updates and schedule batch completion verification asynchronously with 200ms debouncing, replacing previous in-transaction logic. This architectural shift moves from immediate transactional completion to separate granular updates followed by background completion checks.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The pull request description is entirely missing; no content was provided following the required template with sections for Testing, Changelog, and Screenshots.	Add a complete PR description following the template, including issue reference, testing steps, changelog entry, and any relevant screenshots or context.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: redesigning batch completion logic to address row-level contention issues on BatchTaskRun.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

🧹 Recent nitpick comments

apps/webapp/app/v3/services/batchTriggerV3.server.ts (1)
1043-1050: Log message may be misleading on retry path.

The log message states "scheduling retry" but when isRetry is true, the error is thrown instead of scheduling a new retry. Consider making the message more accurate.
♻️ Suggested improvement
   } catch (error) {
     if (isPrismaRetriableError(error) || isPrismaRaceConditionError(error)) {
-      logger.error("completeBatchTaskRunItemV3 failed, scheduling retry", {
+      logger.error("completeBatchTaskRunItemV3 failed with retriable error", {
         itemId,
         batchTaskRunId,
         error,
         retryAttempt,
         isRetry,
       });

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d893b26 and 85b84c2.

📒 Files selected for processing (2)

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

🧰 Additional context used

📓 Path-based instructions (8)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.{ts,tsx}: Use types over interfaces for TypeScript
Avoid using enums; prefer string unions or const objects instead

**/*.{ts,tsx}: Always import tasks from @trigger.dev/sdk, never use @trigger.dev/sdk/v3 or deprecated client.defineJob pattern
Every Trigger.dev task must be exported and have a unique id property with no timeouts in the run function

Files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

{packages/core,apps/webapp}/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use zod for validation in packages/core and apps/webapp

Files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use function declarations instead of default exports

Import from @trigger.dev/core using subpaths only, never import from root

Files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

apps/webapp/app/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/webapp.mdc)

Access all environment variables through the env export of env.server.ts instead of directly accessing process.env in the Trigger.dev webapp

Files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

apps/webapp/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/webapp.mdc)

apps/webapp/**/*.{ts,tsx}: When importing from @trigger.dev/core in the webapp, use subpath exports from the package.json instead of importing from the root path
Follow the Remix 2.1.0 and Express server conventions when updating the main trigger.dev webapp

Access environment variables via env export from apps/webapp/app/env.server.ts, never use process.env directly

Files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

**/*.ts

📄 CodeRabbit inference engine (.cursor/rules/otel-metrics.mdc)

**/*.ts: When creating or editing OTEL metrics (counters, histograms, gauges), ensure metric attributes have low cardinality by using only enums, booleans, bounded error codes, or bounded shard IDs
Do not use high-cardinality attributes in OTEL metrics such as UUIDs/IDs (envId, userId, runId, projectId, organizationId), unbounded integers (itemCount, batchSize, retryCount), timestamps (createdAt, startTime), or free-form strings (errorMessage, taskName, queueName)
When exporting OTEL metrics via OTLP to Prometheus, be aware that the exporter automatically adds unit suffixes to metric names (e.g., 'my_duration_ms' becomes 'my_duration_ms_milliseconds', 'my_counter' becomes 'my_counter_total'). Account for these transformations when writing Grafana dashboards or Prometheus queries

Files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

**/*.{js,ts,jsx,tsx,json,md,yaml,yml}

📄 CodeRabbit inference engine (AGENTS.md)

Format code using Prettier before committing

Files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

apps/webapp/app/v3/services/**/*.server.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/webapp.mdc)

Organize services in the webapp following the pattern app/v3/services/*/*.server.ts

Files:

apps/webapp/app/v3/services/batchTriggerV3.server.ts

🧠 Learnings (18)

📓 Common learnings

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `batch.triggerByTaskAndWait()` to batch trigger tasks by passing task instances and wait for results

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `batch.trigger()` to trigger multiple different tasks at once from backend code

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `batch.trigger()` to trigger multiple different tasks at once from backend code

Applied to files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `yourTask.batchTrigger()` to trigger multiple runs of a task from inside another task

Applied to files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `tasks.batchTrigger()` to trigger multiple runs of a single task with different payloads

Applied to files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `batch.triggerByTaskAndWait()` to batch trigger tasks by passing task instances and wait for results

Applied to files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `runs.subscribeToBatch()` to subscribe to changes for all runs in a batch

Applied to files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `batch.triggerByTask()` to batch trigger tasks by passing task instances for static task sets

Applied to files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use the `task()` function from `trigger.dev/sdk/v3` to define tasks with id and run properties

Applied to files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `batch.triggerAndWait()` to batch trigger multiple different tasks and wait for results

Applied to files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `yourTask.batchTriggerAndWait()` to batch trigger tasks and wait for all results from a parent task

Applied to files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2026-01-15T11:50:06.067Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-15T11:50:06.067Z
Learning: Applies to **/*.{ts,tsx} : Always import tasks from `trigger.dev/sdk`, never use `trigger.dev/sdk/v3` or deprecated `client.defineJob` pattern

Applied to files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use logger methods (debug, log, info, warn, error) from `trigger.dev/sdk/v3` for structured logging in tasks

Applied to files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `tasks.trigger()` with type-only imports to trigger tasks from backend code without importing the task implementation

Applied to files:

apps/webapp/app/v3/legacyRunEngineWorker.server.ts
apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `schemaTask()` from `trigger.dev/sdk/v3` with Zod schema for payload validation

Applied to files:

apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:26:37.432Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-27T16:26:37.432Z
Learning: Applies to internal-packages/database/**/*.{ts,tsx} : Use Prisma for database interactions in internal-packages/database with PostgreSQL

Applied to files:

apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:26:58.661Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/webapp.mdc:0-0
Timestamp: 2025-11-27T16:26:58.661Z
Learning: Leverage the PostgreSQL database through the `trigger.dev/database` Prisma 6.14.0 client in the webapp for all data access patterns

Applied to files:

apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Attach metadata to task runs using the metadata option when triggering, and access/update it inside runs using metadata functions

Applied to files:

apps/webapp/app/v3/services/batchTriggerV3.server.ts

📚 Learning: 2025-11-27T16:27:35.304Z

Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Subscribe to run updates using `runs.subscribeToRun()` for realtime monitoring of task execution

Applied to files:

apps/webapp/app/v3/services/batchTriggerV3.server.ts

🧬 Code graph analysis (1)

apps/webapp/app/v3/legacyRunEngineWorker.server.ts (1)

apps/webapp/app/v3/services/batchTriggerV3.server.ts (1)

tryCompleteBatchV3 (937-998)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (21)

GitHub Check: units / internal / 🧪 Unit Tests: Internal (7, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (3, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (5, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (8, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (6, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (6, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (3, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (7, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (2, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (4, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (1, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (8, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (2, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (5, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (4, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (1, 8)
GitHub Check: e2e / 🧪 CLI v3 tests (ubuntu-latest - npm)
GitHub Check: units / packages / 🧪 Unit Tests: Packages (1, 1)
GitHub Check: e2e / 🧪 CLI v3 tests (windows-latest - npm)
GitHub Check: e2e / 🧪 CLI v3 tests (windows-latest - pnpm)
GitHub Check: typecheck / typecheck

🔇 Additional comments (5)

apps/webapp/app/v3/services/batchTriggerV3.server.ts (2)

937-998: Well-designed idempotent batch completion function.

The implementation correctly handles idempotency through multiple guard conditions and the updateMany with status: "PENDING" filter. The separation of read (count) and write (update) operations is acceptable here since the function will be invoked again if a race occurs.

One minor observation: the completedCount stored on line 985 reflects the count at read time, which could be slightly stale if another item completes between the count and update. This is acceptable for audit/display purposes since correctness is ensured by the idempotent update pattern.

1019-1041: Effective debounce pattern for reducing contention.

The approach of updating items individually with updateMany (idempotent via status check) and then scheduling a debounced completion check is a solid architectural improvement. The debounce behavior (same job ID with availableAt overwrites previous) effectively coalesces multiple rapid item completions into a single batch completion check.

apps/webapp/app/v3/legacyRunEngineWorker.server.ts (3)

8-11: LGTM!

Import correctly updated to include the new tryCompleteBatchV3 function.

56-65: Catalog entry looks appropriate for debounced completion checks.

The 30-second visibility timeout and 5 max retries are reasonable for a lightweight completion check operation. The schema correctly matches the payload structure used when enqueueing from completeBatchTaskRunItemV3.

101-103: LGTM!

Job handler correctly delegates to tryCompleteBatchV3 with the appropriate parameters.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

vibe-kanban-cloud · 2026-01-23T15:24:06Z

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.

fix(v3): redesign of batch completion to prevent heavy row-level cont…

85b84c2

…ention on the BatchTaskRun

ericallam marked this pull request as ready for review January 23, 2026 15:48

matt-aitken approved these changes Jan 23, 2026

View reviewed changes

matt-aitken merged commit 022f69c into main Jan 23, 2026
32 checks passed

matt-aitken deleted the fix/v3-batch-trigger-completion-contention branch January 23, 2026 15:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(v3): redesign of batch completion to prevent heavy row-level contention on the BatchTaskRun#2930

fix(v3): redesign of batch completion to prevent heavy row-level contention on the BatchTaskRun#2930
matt-aitken merged 1 commit intomainfrom
fix/v3-batch-trigger-completion-contention

ericallam commented Jan 23, 2026

Uh oh!

changeset-bot bot commented Jan 23, 2026

Uh oh!

coderabbitai bot commented Jan 23, 2026 •

edited

Loading

Uh oh!

vibe-kanban-cloud bot commented Jan 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ericallam commented Jan 23, 2026

Uh oh!

changeset-bot bot commented Jan 23, 2026

⚠️ No Changeset found

Uh oh!

coderabbitai bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Estimated code review effort

Uh oh!

vibe-kanban-cloud bot commented Jan 23, 2026

Review Complete

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coderabbitai bot commented Jan 23, 2026 •

edited

Loading